home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / cmds / pmake / customs / README < prev    next >
Encoding:
Text File  |  1989-11-15  |  5.4 KB  |  106 lines
  1. 10/29/89
  2.     The files in this directory implement Customs -- a remote execution
  3. facility for PMake. Customs is designed to run on a network of machines with a
  4. consistent, shared filesystem. It requires Sun RPC only because I never got
  5. around to updating the logging functions to provide byte-swapping functions --
  6. they use XDR (eXternal Data Representation) routines instead.
  7.  
  8. I wrote this primarily as a research project, so it doesn't have all the bells
  9. and whistles one might expect.
  10.  
  11.     Note that I make no claim to its security. To quote from the standard
  12. copyright notice:
  13.  
  14.      Permission to use, copy, modify, and distribute this
  15.       software and its documentation for any purpose and without
  16.        fee is hereby granted, provided that the above copyright
  17. notice appears in all copies.  Neither the University of California nor
  18.  Adam de Boor makes any representations about the suitability of this
  19.       software for any purpose.  It is provided "as is" without
  20.              express or implied warranty.
  21.  
  22. The best that can be said for the security of the system is that any
  23. misuse can be logged, though not prevented.
  24.  
  25. *******************************************************************************
  26.  
  27. Customs is set up as a single server process (which must run on each
  28. participating machine) and a suite of client/control programs, one of which is
  29. PMake. The Customs server ("agent") is responsible for determining the avail-
  30. ability of the local machine, based on certain criteria you can modify, and
  31. to manage jobs from other participating machines.
  32.  
  33. A single server is designated as the master agent and is additionally
  34. responsible for noting when a machine goes down, from which machines
  35. any given machine will accept jobs and parcelling out available
  36. machines to requesting clients. The job of master is not given to any
  37. one machine but, rather, is decided among the active agents whenever
  38. the previous master dies.
  39.  
  40. A bit of logging (restarts, aborts, swap space available, things like that)
  41. is done to a log file, but actual usage is only logged by another program.
  42. I use the logging daemon mostly for debugging, but you may want it to detect
  43. abuses. If the system is used heavily, however, it will take a lot of disk
  44. space -- the messages are verbose.
  45.  
  46. Clients are provided to:
  47.     - alter the availability criteria for the local machine (importquota)
  48.     - find the status of all registered hosts on the net (reginfo).
  49.     - abort, restart or ping any customs agent on the network (cctrl).
  50.     - export a command from the shell (export).
  51.     - accept log information from all hosts on the net (logd).
  52.  
  53. *******************************************************************************
  54.  
  55. To make the system, you should have already made PMake to run locally.
  56. Once this is done, you should (all this happens in the customs subdirectory):
  57.  
  58.     1) if your compiler doesn't support the void * type used by the
  59.        rpc system, change the definition of Rpc_Opaque in rpc.h.
  60.     2) Change INSTALL_DIR in the Makefile to the correct place. (Also
  61.        change the definition of CC if you don't have gcc). Set OSOBJ
  62.        to contain the name of the proper os-dependent .o file for your
  63.        system.
  64.     3) Type "pmake install". If this doesn't work, you'll have to fix
  65.        it...
  66.     4) Add entries for "customs", both tcp and udp protocols, in
  67.        /etc/services. Any port will do (I use 8231 for both). You
  68.        can make it less than 1024 if you want to add that extra little
  69.        bit of security -- the daemon will be running as root so it can
  70.            use those ports. All communication between agents is checked to
  71.            make sure it's actually coming from the correct udp port to
  72.        forestall fraud, so placing the port in the secure range will
  73.        help some.
  74.     5) Place the same port numbers in customs.h in the DEF_*_PORT
  75.        constants. I added these because yellow pages doesn't behave
  76.        well under load, especially when fetching services, and more
  77.        often than I liked, pmakes would fail with "customs/udp unknown"
  78.        errors.
  79.     6) Read the manual page for customs (../doc/customs.8) to decide
  80.        what initial criteria should be used to determine the machine's
  81.        availability, then place a line like
  82.         if [ -f /etc/customs ]; then
  83.             echo ' customs'                >/dev/console
  84.             /etc/customs -arch 1 ALL
  85.         fi
  86.        at the proper place in your /etc/rc.local file (I put it in the
  87.        local daemons section. note that Sun requires the echo to be done in
  88.        a subshell to avoid attaching the shell running the script to a
  89.        controlling terminal). -arch tells the agent its architecture
  90.        number, which is used to support the .EXPORTSAME attribute in PMake.
  91.        There should be a unique number for each type of machine on the
  92.        network. You can also have several different sub-nets of agents
  93.        on the same network by assigning each individual sub-net a different
  94.        network number with the -net flag. For maximum efficiency, however,
  95.        you want as many machines on the net as possible.
  96.     7) Once the system is compiled and installed on all the different
  97.        machines, start up a customs agent on each one.
  98.     8) After about 30 seconds (to give them time to elect a Master Agent),
  99.        execute 'reginfo' to make sure all of them came up OK. If they're
  100.        registered but say 'host down', don't worry about it unless it
  101.        persists beyond whatever availability interval you chose.
  102.  
  103. *******************************************************************************
  104.     $Id: README,v 1.3 89/11/14 13:46:33 adam Exp $
  105.  
  106.